home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Apple WWDC 1996
/
WWDC96_1996 (CD).toast
/
Technology Materials
/
MacOS 8 Resources
/
Developer Tools
/
Mac OS 8 Interfaces & Libraries
/
Interfaces
/
CIncludes
/
CodeFragments.h
< prev
next >
Wrap
C/C++ Source or Header
|
1996-05-01
|
21KB
|
591 lines
/*
File: CodeFragments.h
Contains: Public Code Fragment Manager Interfaces.
Version: Technology: System 7 and System 8
Release: Universal Interfaces 3.0d3 on Copland DR1
Copyright: © 1984-1996 by Apple Computer, Inc. All rights reserved.
Bugs?: If you find a problem with this file, send the file and version
information (from above) and the problem description to:
Internet: apple.bugs@applelink.apple.com
AppleLink: APPLE.BUGS
*/
/*
*
===========================================================================================
The Code Fragment Manager API
=============================
*/
#ifndef __CODEFRAGMENTS__
#define __CODEFRAGMENTS__
#ifndef __TYPES__
#include <Types.h>
#endif
#ifndef __FILES__
#include <Files.h>
#endif
#if FOR_SYSTEM8_PREEMPTIVE
#ifndef __KERNEL__
#include <Kernel.h>
#endif
#ifndef __FILEMANAGERTYPES__
#include <FileManagerTypes.h>
#endif
#ifndef __TEXTOBJECTS__
#include <TextObjects.h>
#endif
#endif
#ifdef __cplusplus
extern "C" {
#endif
#if PRAGMA_IMPORT_SUPPORTED
#pragma import on
#endif
#if PRAGMA_ALIGN_SUPPORTED
#pragma options align=mac68k
#endif
/*
ß
===========================================================================================
Universal types and constants
=============================
*/
#if FOR_SYSTEM7_AND_SYSTEM8_PREEMPTIVE
/*
----------------------------------------------------------------------------
These declarations are for System 7 and all System 8 execution environments.
*/
enum {
kCFragResourceType = 'cfrg',
kCFragResourceID = 0,
kCFragLibraryFileType = 'shlb',
kCFragAllFileTypes = 0xFFFFFFFF
};
typedef OSType CFragArchitecture;
enum {
kPowerPCCFragArch = 'pwpc',
kMotorola68KCFragArch = 'm68k',
kAnyCFragArch = 0x3F3F3F3F
};
#if GENERATINGPOWERPC
enum {
kCompiledCFragArch = kPowerPCCFragArch
};
#endif
#if GENERATING68K
enum {
kCompiledCFragArch = kMotorola68KCFragArch
};
#endif
typedef UInt32 CFragVersionNumber;
enum {
kNullCFragVersion = 0,
kWildcardCFragVersion = 0xFFFFFFFF
};
typedef UInt8 CFragUsage;
enum {
kImportLibraryCFrag = 0, /* Standard CFM import library.*/
kApplicationCFrag = 1, /* Macintosh application.*/
kDropInAdditionCFrag = 2 /* Private extension to an application or library.*/
};
enum {
kIsCompleteCFrag = 0, /* A "base" fragment, not an update.*/
kFirstCFragUpdate = 1 /* The first update, others are numbered 2, 3, ...*/
};
enum {
kCFragGoesToEOF = 0
};
typedef UInt8 CFragLocatorKind;
enum {
kMemoryCFragLocator = 0, /* Container is already addressable.*/
kDataForkCFragLocator = 1, /* Container is in a file's data fork.*/
kResourceCFragLocator = 2 /* Container is in a file's resource fork.*/
};
/*
--------------------------------------------------------------------------------------
A 'cfrg' resource consists of a header followed by a sequence of variable length
members. The constant kDefaultCFragNameLen only provides for a legal ANSI declaration
and for a reasonable display in a debugger. The actual name field is cut to fit.
There may be "extensions" after the name, the memberSize field includes them. The
general form of an extension is a 16 bit type code followed by a 16 bit size in bytes.
Only one standard extension type is defined at present, it is used by SOM's searching
mechanism.
*/
union CFragUsage1Union { /* ! Meaning differs depending on value of "usage".*/
UInt32 appStackSize; /* If the fragment is an application. (Not used by CFM!)*/
};
typedef union CFragUsage1Union CFragUsage1Union;
union CFragUsage2Union { /* ! Meaning differs depending on value of "usage".*/
SInt16 appSubdirID; /* If the fragment is an application.*/
};
typedef union CFragUsage2Union CFragUsage2Union;
union CFragWhere1Union { /* ! Meaning differs depending on value of "where".*/
UInt32 spaceID; /* If the fragment is in memory. (Actually an AddressSpaceID.)*/
OSType forkKind; /* If the fragment is in an arbitrary byte stream fork.*/
};
typedef union CFragWhere1Union CFragWhere1Union;
union CFragWhere2Union { /* ! Meaning differs depending on value of "where".*/
UInt16 forkInstance; /* If the fragment is in an arbitrary byte stream fork.*/
};
typedef union CFragWhere2Union CFragWhere2Union;
enum {
kDefaultCFragNameLen = 16
};
struct CFragResourceMember {
CFragArchitecture architecture;
UInt16 reservedA; /* ! Must be zero!*/
UInt8 reservedB; /* ! Must be zero!*/
UInt8 updateLevel;
CFragVersionNumber currentVersion;
CFragVersionNumber oldDefVersion;
CFragUsage1Union uUsage1;
CFragUsage2Union uUsage2;
CFragUsage usage;
CFragLocatorKind where;
UInt32 offset;
UInt32 length;
CFragWhere1Union uWhere1;
CFragWhere2Union uWhere2;
UInt16 extensionCount; /* The number of extensions beyond the name.*/
UInt16 memberSize; /* Size in bytes, includes all extensions.*/
unsigned char name[16]; /* ! Actually a sized PString.*/
};
typedef struct CFragResourceMember CFragResourceMember;
typedef CFragResourceMember *CFragResourceMemberPtr;
struct CFragResourceExtensionHeader {
UInt16 extensionKind;
UInt16 extensionSize;
};
typedef struct CFragResourceExtensionHeader CFragResourceExtensionHeader;
typedef CFragResourceExtensionHeader *CFragResourceExtensionHeaderPtr;
struct CFragResourceSearchExtension {
CFragResourceExtensionHeader header;
OSType libKind;
unsigned char qualifiers[1]; /* ! Actually four PStrings.*/
};
typedef struct CFragResourceSearchExtension CFragResourceSearchExtension;
typedef CFragResourceSearchExtension *CFragResourceSearchExtensionPtr;
enum {
kCFragResourceSearchExtensionKind = 0x30EE
};
struct CFragResource {
UInt32 reservedA; /* ! Must be zero!*/
UInt32 reservedB; /* ! Must be zero!*/
UInt16 reservedC; /* ! Must be zero!*/
UInt16 version;
UInt32 reservedD; /* ! Must be zero!*/
UInt32 reservedE; /* ! Must be zero!*/
UInt32 reservedF; /* ! Must be zero!*/
UInt32 reservedG; /* ! Must be zero!*/
UInt16 reservedH; /* ! Must be zero!*/
UInt16 memberCount;
CFragResourceMember firstMember;
};
typedef struct CFragResource CFragResource;
typedef CFragResource *CFragResourcePtr;
enum {
kCurrCFragResourceVersion = 1
};
#define AlignToFour(aValue) (((aValue) + 3) & ~3)
#define kBaseCFragResourceMemberSize (offsetof ( CFragResourceMember, name ) )
#define kBaseCFragResourceSize (offsetof ( CFragResource, firstMember.name ) )
#define NextCFragResourceMemberPtr(aMemberPtr) \
((CFragResourceMemberPtr) ((BytePtr)aMemberPtr + aMemberPtr->memberSize))
#define FirstCFragResourceExtensionPtr(aMemberPtr) \
((CFragResourceExtensionHeaderPtr) ((BytePtr)aMemberPtr + \
AlignToFour ( kBaseCFragResourceMemberSize + \
aMemberPtr->name[0] + 1 ) ))
#define NextCFragResourceExtensionPtr(anExtensionPtr) \
((CFragResourceExtensionHeaderPtr) ((BytePtr)anExtensionPtr + \
((CFragResourceExtensionHeaderPtr)anExtensionPtr)->extensionSize ))
#define FirstCFragResourceSearchQualifier(searchExtensionPtr) \
((StringPtr) ((BytePtr)searchExtensionPtr + \
offsetof ( CFragResourceSearchExtension, qualifiers ) ))
#define NextCFragResourceSearchQualifier(searchQualifierPtr) \
((StringPtr) ((BytePtr)searchQualifierPtr + searchQualifierPtr[0] + 1))
typedef struct OpaqueCFragConnectionID* CFragConnectionID;
typedef struct OpaqueCFragClosureID* CFragClosureID;
typedef struct OpaqueCFragContainerID* CFragContainerID;
typedef struct OpaqueCFragContextID* CFragContextID;
typedef UInt32 CFragLoadOptions;
enum {
kLoadCFrag = 0x0001, /* Try to use existing copy, load if not found.*/
kFindCFrag = 0x0002, /* Try find an existing copy, don't load if not found.*/
kPrivateCFragCopy = kLoadCFrag | 0x0004 /* Load a new private copy.*/
};
enum {
kUnresolvedCFragSymbolAddress = 0
};
typedef UInt8 CFragSymbolClass;
enum {
kCodeCFragSymbol = 0,
kDataCFragSymbol = 1,
kTVectorCFragSymbol = 2,
kTOCCFragSymbol = 3,
kGlueCFragSymbol = 4
};
#endif
/*
ß
===========================================================================================
System 7 Services (Deprecated in System 8)
==========================================
*/
#if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
/*
---------------------------------------------------------------------------------
These declarations are for System 7 and the System 8 cooperative environment, but
should be avoided under System 8. Better alternatives exist for System 8.
*/
#define IsFileLocation(where) \
( ((where) == kDataForkCFragLocator) || ((where) == kResourceCFragLocator) )
extern pascal OSErr GetSharedLibrary(ConstStr63Param libName, CFragArchitecture archType, CFragLoadOptions loadFlags, CFragConnectionID *connID, Ptr *mainAddr, Str255 errMessage)
THREEWORDINLINE(0x3F3C, 0x0001, 0xAA5A);
extern pascal OSErr GetDiskFragment(const FSSpec *fileSpec, UInt32 offset, UInt32 length, ConstStr63Param fragName, CFragLoadOptions loadFlags, CFragConnectionID *connID, Ptr *mainAddr, Str255 errMessage)
THREEWORDINLINE(0x3F3C, 0x0002, 0xAA5A);
extern pascal OSErr GetMemFragment(void *memAddr, UInt32 length, ConstStr63Param fragName, CFragLoadOptions loadFlags, CFragConnectionID *connID, Ptr *mainAddr, Str255 errMessage)
THREEWORDINLINE(0x3F3C, 0x0003, 0xAA5A);
extern pascal OSErr CloseConnection(CFragConnectionID *connID)
THREEWORDINLINE(0x3F3C, 0x0004, 0xAA5A);
extern pascal OSErr FindSymbol(CFragConnectionID connID, ConstStr255Param symName, Ptr *symAddr, CFragSymbolClass *symClass)
THREEWORDINLINE(0x3F3C, 0x0005, 0xAA5A);
extern pascal OSErr CountSymbols(CFragConnectionID connID, long *symCount)
THREEWORDINLINE(0x3F3C, 0x0006, 0xAA5A);
extern pascal OSErr GetIndSymbol(CFragConnectionID connID, long symIndex, Str255 symName, Ptr *symAddr, CFragSymbolClass *symClass)
THREEWORDINLINE(0x3F3C, 0x0007, 0xAA5A);
#endif
/*
ß
===========================================================================================
System 8 Services (Not available in System 7)
=============================================
*/
#if FOR_SYSTEM8_PREEMPTIVE
/*
---------------------------------------------------------------------------------
These declarations are for all System 8 execution environments, but not System 7.
*/
enum {
kPatchCFragUpdateLevel = 255
};
enum {
kByteStreamCFragLocator = 3,
kNamedFragmentCFragLocator = 4
};
enum {
kNamedLibraryCFragLocator = kNamedFragmentCFragLocator /* !!! Remove in D12!*/
};
enum {
kPrivilegedCFragMask = 0x0010, /* ! May be removed in the future!*/
kResidentCFragMask = 0x0020, /* ! May be removed in the future!*/
kTreatCFragAsLibraryMask = 0x0040 /* Used in GetXyzFragment to recognize by name too.*/
};
enum {
kPrivilegedCFragFlag = kPrivilegedCFragMask, /* !!! Remove in D12!*/
kResidentCFragFlag = kResidentCFragMask /* !!! Remove in D12!*/
};
enum {
kMainCFragSymbolIndex = -1,
kInitCFragSymbolIndex = -2,
kTermCFragSymbolIndex = -3
};
struct CFragRegisteredFileInfo {
FSObjectRef fileRef;
OSType fileType;
ItemCount nestingDepth;
};
typedef struct CFragRegisteredFileInfo CFragRegisteredFileInfo;
enum {
kCFragRegisteredFileInfoVersion = 0x00010001
};
typedef UInt8 CFragCompatibility;
enum {
CFragBothCompatible = 0,
CFragClientTooOld = 1,
CFragProviderTooOld = 2
};
typedef UInt32 CFragShortVersionPair;
#define ComposeCFragShortVersionPair(current,older) (current << 16 | older)
#define GetCFragShortVersionCurrent(version) (version >> 16)
#define GetCFragShortVersionOlder(version) (version & 0xFFFF)
extern CFragCompatibility CFragCheckCompatibility(UInt32 clientPreferredVersion, UInt32 clientOldImpVersion, UInt32 providerCurrentVersion, UInt32 providerOldDefVersion);
extern CFragCompatibility CFragCheckShortCompatibility(UInt32 clientVersions, UInt32 providerVersions);
extern Boolean CFragHasFileLocation(CFragLocatorKind where);
extern Boolean CFragHasUnresolvedImports(CFragConnectionID connID);
extern OSStatus CFragPrepareNamedFragment(ConstStr63Param fragName, CFragUsage usage, CFragArchitecture archType, CFragVersionNumber preferredVersion, CFragVersionNumber oldestVersion, CFragLoadOptions loadFlags, CFragConnectionID *connID, LogicalAddress *mainAddr, TextObject optErrMsg);
extern OSStatus CFragPrepareFromDiskFork(FSObjectRef fileSpec, FSForkType forkTag, ItemCount forkInstance, ByteCount offset, ByteCount length, ConstStr63Param fragName, CFragLoadOptions loadFlags, CFragConnectionID *connID, LogicalAddress *mainAddr, TextObject optErrMsg);
extern OSStatus CFragPrepareFromMemory(LogicalAddress fragAddr, ByteCount length, ConstStr63Param fragName, CFragLoadOptions loadFlags, CFragConnectionID *connID, LogicalAddress *mainAddr, TextObject optErrMsg);
extern OSStatus CFragCloseConnection(CFragConnectionID *connID);
extern OSStatus CFragFindNamedSymbol(CFragConnectionID connID, ConstStr255Param symName, LogicalAddress *symAddr, CFragSymbolClass *symClass);
extern OSStatus CFragCountSymbols(CFragConnectionID connID, ItemCount *symCount);
extern OSStatus CFragGetIndexedSymbol(CFragConnectionID connID, SInt32 symIndex, Str255 symName, LogicalAddress *symAddr, CFragSymbolClass *symClass);
extern OSStatus CFragGetFileSpec(CFragConnectionID connectionID, FSObjectRef *fileSpec);
extern OSStatus CFragGetFragmentName(CFragConnectionID connectionID, Str63 name);
extern OSStatus CFragRegisterFileFragments(KernelProcessID processID, FSObjectRef fileSpec, OSType fileType, ItemCount nestingDepth);
extern OSStatus CFragUnregisterFileFragments(KernelProcessID processID, FSObjectRef fileSpec, OSType fileType, ItemCount nestingDepth);
extern OSStatus CFragGetRegisteredFiles(KernelProcessID processID, ItemCount requestedCount, ItemCount *totalCount, PBVersion infoVersion, CFragRegisteredFileInfo *registeredFiles);
#endif
/*
ß
===========================================================================================
Initialization & Termination Routines
=====================================
-----------------------------------------------------------------------------------------
A fragment's initialization and termination routines are called when a new incarnation of
the fragment is created or destroyed, respectively. Exactly when this occurs depends on
what kinds of section sharing the fragment has and how the fragment is prepared. Import
libraries have at most one incarnation per process. Fragments prepared with option
kPrivateCFragCopy may have many incarnations per process.
The initialization function is passed a pointer to an initialization information structure
and returns an OSErr. If an initialization function returns a non-zero value the entire
closure of which it is a part fails. The CFragInitBlock type has different visible parts
under System 7 and System 8, but is of course the same internally. The C prototype for an
initialization function is:
pascal OSErr CFragInitFunction ( const CFragInitBlock * initBlock );
The termination procedure takes no parameters and returns nothing. The C prototype for a
termination procedure is:
pascal void CFragTermProcedure ( void );
*/
#if FOR_OPAQUE_SYSTEM_DATA_STRUCTURES
/*
--------------------------------------------------------------------------------------
These declarations are the preferred form for System 8, hiding implementation details.
*/
struct CFragOpaqueInitBlock {
KernelProcessID processID;
CFragClosureID closureID;
CFragConnectionID connectionID;
UInt32 reservedA[8];
};
typedef struct CFragOpaqueInitBlock CFragOpaqueInitBlock;
typedef CFragOpaqueInitBlock *CFragOpaqueInitBlockPtr;
typedef CFragOpaqueInitBlock CFragInitBlock;
typedef CFragOpaqueInitBlockPtr CFragInitBlockPtr;
#else
/*
--------------------------------------------------------------------------------------
These declarations are for System 7. They may be used in System 8 but expose details.
*/
struct CFragSystem7MemoryLocator {
LogicalAddress address;
UInt32 length;
Boolean inPlace;
UInt8 reservedA; /* ! Must be zero!*/
UInt16 reservedB; /* ! Must be zero!*/
};
typedef struct CFragSystem7MemoryLocator CFragSystem7MemoryLocator;
struct CFragSystem7DiskFlatLocator {
FSSpecPtr fileSpec;
UInt32 offset;
UInt32 length;
};
typedef struct CFragSystem7DiskFlatLocator CFragSystem7DiskFlatLocator;
/* ! This must have a file specification at the same offset as a disk flat locator!*/
struct CFragSystem7SegmentedLocator {
FSSpecPtr fileSpec;
OSType rsrcType;
SInt16 rsrcID;
UInt16 reservedA; /* ! Must be zero!*/
};
typedef struct CFragSystem7SegmentedLocator CFragSystem7SegmentedLocator;
struct CFragSystem7Locator {
SInt32 where;
union {
CFragSystem7DiskFlatLocator onDisk;
CFragSystem7MemoryLocator inMem;
CFragSystem7SegmentedLocator inSegs;
} u;
};
typedef struct CFragSystem7Locator CFragSystem7Locator;
typedef CFragSystem7Locator *CFragSystem7LocatorPtr;
struct CFragSystem7InitBlock {
CFragContextID contextID;
CFragClosureID closureID;
CFragConnectionID connectionID;
CFragSystem7Locator fragLocator;
StringPtr libName;
UInt32 reservedA; /* ! Must be zero!*/
};
typedef struct CFragSystem7InitBlock CFragSystem7InitBlock;
typedef CFragSystem7InitBlock *CFragSystem7InitBlockPtr;
typedef CFragSystem7InitBlock CFragInitBlock;
typedef CFragSystem7InitBlockPtr CFragInitBlockPtr;
#endif
typedef OSErr (*CFragInitFunction)(const CFragInitBlock *initBlock);
typedef void (*CFragTermProcedure)(void );
/*
ß
===========================================================================================
Old Name Spellings
==================
-------------------------------------------------------------------------------------------
We've tried to reduce the risk of name collisions in the future by introducing the phrase
"CFrag" into constant and type names. The old names are defined below in terms of the new.
*/
#if OLDROUTINENAMES
typedef CFragConnectionID ConnectionID;
typedef CFragLoadOptions LoadFlags;
typedef CFragSymbolClass SymClass;
typedef CFragInitBlock InitBlock;
typedef CFragInitBlockPtr InitBlockPtr;
#if !FOR_OPAQUE_SYSTEM_DATA_STRUCTURES
typedef CFragSystem7MemoryLocator MemFragment;
typedef CFragSystem7DiskFlatLocator DiskFragment;
typedef CFragSystem7SegmentedLocator SegmentedFragment;
typedef CFragSystem7Locator FragmentLocator;
typedef CFragSystem7LocatorPtr FragmentLocatorPtr;
typedef CFragSystem7MemoryLocator CFragHFSMemoryLocator;
typedef CFragSystem7DiskFlatLocator CFragHFSDiskFlatLocator;
typedef CFragSystem7SegmentedLocator CFragHFSSegmentedLocator;
typedef CFragSystem7Locator CFragHFSLocator;
typedef CFragSystem7LocatorPtr CFragHFSLocatorPtr;
#endif
enum {
kPowerPCArch = kPowerPCCFragArch,
kMotorola68KArch = kMotorola68KCFragArch,
kAnyArchType = kAnyCFragArch,
kNoLibName = 0,
kNoConnectionID = 0,
kLoadLib = kLoadCFrag,
kFindLib = kFindCFrag,
kNewCFragCopy = kPrivateCFragCopy,
kLoadNewCopy = kPrivateCFragCopy,
kUseInPlace = 0x80,
kCodeSym = kCodeCFragSymbol,
kDataSym = kDataCFragSymbol,
kTVectSym = kTVectorCFragSymbol,
kTOCSym = kTOCCFragSymbol,
kGlueSym = kGlueCFragSymbol,
kInMem = kMemoryCFragLocator,
kOnDiskFlat = kDataForkCFragLocator,
kOnDiskSegmented = kResourceCFragLocator,
kIsLib = kImportLibraryCFrag,
kIsApp = kApplicationCFrag,
kIsDropIn = kDropInAdditionCFrag,
kFullLib = kIsCompleteCFrag,
kUpdateLib = kFirstCFragUpdate,
kWholeFork = kCFragGoesToEOF,
kCFMRsrcType = kCFragResourceType,
kCFMRsrcID = kCFragResourceID,
kSHLBFileType = kCFragLibraryFileType,
kUnresolvedSymbolAddress = kUnresolvedCFragSymbolAddress
};
enum {
kPowerPC = kPowerPCCFragArch,
kMotorola68K = kMotorola68KCFragArch
};
#endif
#if PRAGMA_ALIGN_SUPPORTED
#pragma options align=reset
#endif
#if PRAGMA_IMPORT_SUPPORTED
#pragma import off
#endif
#ifdef __cplusplus
}
#endif
#endif /* __CODEFRAGMENTS__ */